home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / src / exampleCode / stereo / GL_5.2 / README < prev    next >
Encoding:
Text File  |  1994-08-02  |  11.4 KB  |  246 lines
  1.  
  2.             ~4Dgifts/toolbox/src/exampleCode/stereo/GL_5.2 README
  3.  
  4.  
  5.  ==============================================================================
  6.  |                  README for StereoView Examples                            |
  7.  |                                                             1/11/94        |
  8.  ==============================================================================
  9.  This example code is derived from an older 4Dgifts directory that showed
  10.  how to use the original SGI StereoView implementation.  In IRIX 5.2 and
  11.  later, SGI engineers enhanced the Xsgi X server to provide a more
  12.  sophisticated stereo implementation on some graphics devices.  This
  13.  new implementation will be refered to as software-stereo-in-a-window or
  14.  SoftStereo.   It has many of the characteristics of hardware-stereo-in-a-
  15.  window on Reality Engine but at a reduced resolution and price ;)
  16.  
  17.  At the time these demos were put together it appeared likely that 
  18.  SoftStereo will be supported under IRIX 5.2 on:
  19. ===>>> THIS LIST IS SUBJECT TO ADDITIONS OR DELETIONS WITHOUT NOTICE.  <<<<====
  20.                    XS
  21.                    XZ
  22.                    Elan
  23.                    Extreme
  24.                    Personal Iris GR1.2
  25.            XL (aka Indy graphics)
  26. ===>>> THIS LIST IS SUBJECT TO ADDITIONS OR DELETIONS WITHOUT NOTICE.  <<<<====
  27.  
  28.  STEREO API's
  29.  
  30.  SoftStereo will use an API closely resembling the one use on Reality
  31.  Engine and in OpenGL.  It uses only one window with two internal buffers
  32.  which may be refered to as STEREO_BUFFER_LEFT and STEREO_BUFFER_RIGHT.
  33.  The original SGI stereo implementation uses two windows which are normally
  34.  refered to as top and bottom.
  35.  
  36.  SoftStereo offers a number of advantages over the old stereo implementation:
  37.  
  38.      - X and Motif windows are displayed to both eyes without any extra
  39.        effort on the part of the application
  40.  
  41.      - All windows are usable and there is no transparency or wrap around
  42.        between top and bottom buffers like the old stereo method
  43.  
  44.      - The API, when fully implemented, will be easier to use and 
  45.        consistent with stereo API's on Reality Engine and OpenGL.
  46.  
  47.  Our apologies when you encounter example code that is hastily prepared
  48.  to use the new SoftStereo mode.  Also apologies for the mixing of new
  49.  and old stereo API examples in one directory.  It is hoped the examples
  50.  provided for SoftStereo should be usable in perpetuity although somewhat
  51.  more streamlined versions may be available in the future.
  52.  
  53.  The next release will hopefully provide better coordinated examples of:
  54.  
  55.      - Traditional stereo
  56.      - SoftStereo
  57.      - hardware-stereo-in-a-window
  58.      - OpenGL stereo
  59.  
  60.  Promises, promises.
  61.  
  62.  ==============================================================================
  63.  CONTENTS
  64.  ==============================================================================
  65.  
  66.      This directory contains source for the following programming examples:
  67.  
  68.      libstereo.a : contains a set of support routines for programming stereo
  69.                    --built from onoffstereo.c, stereopersp.c, stereowin.c,
  70.                    and stereo.h
  71.            backg : creates a simple stereo background
  72.             grid : draws a simple stereo diagnostic program grid (viewed w/a
  73.                    closed left eye, a red grid and the word "RIGHT" is 
  74.                    visible, viewed w/a closed right eye, a blue grid and the
  75.                    word "LEFT" is visible)
  76.   on/off -stereo : simple routines for turning on and off stereo mode.
  77.  
  78.  NEW ADDITIONS
  79.      nestedcubes : a simple stereo application modified to support
  80.                    SoftStereo
  81.   CheckExtension : An X program to test for the new SGI SoftStereo-in-a-window
  82.                    implementation available on some platforms under IRIX 5.2.
  83.            Run this included (built on 5.1) executable to see if the
  84.            required "SoftStereo extension" is found on the machine 
  85.            you are running on or not.
  86.      SGIStereo.o : A 4.0.5 object with XSGI extensions that allows querying
  87.                    for and using SoftStereo under IRIX 5.2 from 4.0.5
  88.                    built applications
  89.        libXext.a : A sample 5.1 archive with XSGI extansions.  This should
  90.                    NOT be used if you are compiling on IRIX on 5.2
  91.                    or later since the library in /usr/lib surpasses this
  92.            get.h : An example header file with definitions for the two
  93.                    new SoftStereo modes STR_TOP and STR_BOT.  This should
  94.                    NOT be used if you are compiling on IRIX on 5.2
  95.                    or later since the header in /usr/include/gl surpasses this
  96.  
  97.  ==============================================================================
  98.  MAKING THE EXAMPLES
  99.  ==============================================================================
  100.  
  101.      The Makefile in this example is set to build for IRIX 5.2 by default.
  102.      You will need to comment out one line in the Makefile and uncomment
  103.      one other for IRIX 4.0.5 makes.
  104.  
  105.      If you are working on 5.2 or later you should use the IRIX versions
  106.      of the following, instead of the ones included in this directory:
  107.  
  108.          libXext.a    in /usr/lib/libXext.a or libXext.so
  109.          SGIStereo.h  in /usr/include/X11/extensions/SGIStereo.h
  110.  
  111.      To compile--as 4Dgifts user--type 'make' in this directory.  If you 
  112.      are doing this for the first time, make will first build libstereo.a 
  113.      from onoffstereo.c, stereopersp.c, stereowin.c, and, stereo.h.
  114.  
  115.  
  116.         If you want to see:           Then execute the command(s):
  117.        ------------------------       ----------------------------
  118.        if stereo works properly       grid
  119.        a fullscreen application       nestedcubes
  120.        a windowed application         backg; sleep 2; nestedcubes -w
  121.        a normal display               offstereo
  122.        if SOftStereo is supported     CheckExtension
  123.  
  124.  
  125.           -------------------------------------------------------
  126.           | You will need IRIX 3.3 or later to run these demos  |
  127.           | in the old full screen stereo mode                  |
  128.           -------------------------------------------------------
  129.           | You will need IRIX 5.2 or later to run the demos    |
  130.           | which use the new SoftStereo-in-a-window mode on    |
  131.       |     XL - XZ - XS - Elan - Extreme - PI GR1.2        |
  132.           -------------------------------------------------------
  133.  
  134.  
  135.  ==============================================================================
  136.  MAKING A STEREO APPLICATION
  137.  ==============================================================================
  138.  
  139.  Here's a short description of what is involved in stereo-izing an application:
  140.      
  141.      1)  SET STEREO MODE
  142.  
  143.          Your application must turn on stereo by issuing a 
  144.          setmonitor(mode) command.  You should check to see if 
  145.          stereo mode is supported by issuing a getgdesc(GD_STEREO)
  146.          command.   Three stereo modes are possible if SoftStereo
  147.          is supported:
  148.  
  149.              STR_RECT - Traditional full screen stereo mode
  150.              STR_BOT  - New SoftStereo-in-a-window stereo using the bottom
  151.                         half of the X display 
  152.              STR_TOP  - New SoftStereo-in-a-window stereo using the top
  153.                         half of the X display
  154.  
  155.          Using the new API your app can inquire if SoftStereo is supported
  156.          with:
  157.  
  158.              if(XSGIStereoQueryExtension(XtDisplay(widget), event, error))
  159.                    sofStereo = TRUE;
  160.  
  161.          Your app can inquire what version of stereo is supported with:
  162.  
  163.              XSGIStereoQueryVersion(XtDisplay(widget), &majorRev, &minorRev);
  164.  
  165.      There are also XSGI extensions available to set some stereo
  166.      characteristics controlled by the X server.  These are for 
  167.      applications with special requirements and are not required by 
  168.      basic stereo applications.
  169.          
  170.      2) CONSTRAIN MOUSE FOR OLD STEREO
  171.  
  172.          Using full screen stereo you should also constrain the mouse to
  173.          the lower half of the screen using a setvaluator() command.
  174.  
  175.          In SoftStereo mode the X server will automatically constrain
  176.          the mouse for you.
  177.  
  178.          (All three of the above-mentioned calls come from the Graphics 
  179.          Library (GL)--consult 3G-section (GL Reference Manual) man 
  180.          pages.)  A routine called stereo_on() in libstereo.a does 
  181.          all of this for you; see the code in onoffstereo.c, and the 
  182.          comments in stereo.h.
  183.      
  184.      3)  WINDOWS
  185.  
  186.          FULL SCREEN STEREO
  187.  
  188.          You must decide if the application should take over the 
  189.          entire screen, or if it should run in (user-resizeable) 
  190.          windows.  If it takes over the entire screen, you should 
  191.          set up two viewports (one for each eye) in the upper and 
  192.          lower halves of the screen.  If it should run in a window,
  193.          you will have to open two windows, one in the upper and 
  194.          one in the lower half of the screen.  If it runs in 
  195.          windows, you will also probably want to put up an 
  196.          appropriate background to cover up all of the regular, 
  197.          non-stereo windows;  see the code in backg for an example.  
  198.          See the code in nestedcubes for an example application, 
  199.          and see stereo.h for some simple support routines for 
  200.          doing stereo in windows.
  201.  
  202.          SOFTSTEREO IN A WINDOW
  203.  
  204.          SoftStereo uses only one window for both eyes.  The X server
  205.          maintains a STEREO_BUFFER_LEFT and a STEREO_BUFFER_RIGHT 
  206.          using just one X window.  X and Motif windows are automatically
  207.          drawn in both buffers so the app doesn't have to deal with this.
  208.          The app does need to draw two copies of GL images with or without
  209.          the projection change for left and right eyes.  You don't
  210.          need to obscure any windows in this mode since all windows
  211.          will be usable except that their apparent height on the screen
  212.          is doubled.  If GL windows are not drawn twice they will be
  213.          visible to only one eye.
  214.      
  215.      3) A stereo application must draw its scene twice, once for the
  216.          left-eye view, and once for the right-eye view.  The 
  217.          'stereopersp' command in libstereo.a can be very useful for 
  218.          generating correct perspective stereo images.  For more 
  219.          information, see the Summer 1989 issue of the "Iris 
  220.          Universe," (pp. 16-18, 20-22) which has a very informative
  221.          article by Thant Tessman about stereo projections.  Again, 
  222.          see the code in nestedcubes for an example using 
  223.          stereopersp().
  224.  
  225.  
  226.  ==============================================================================
  227.  BUGS
  228.  ==============================================================================
  229.  
  230.  It has been observed that some or all of these examples may have the
  231.  left and right eye views reversed.  Due to an impending deadline this
  232.  could not be confirmed or denied by testing.  Testing with stereo
  233.  glasses is the only definitive way to ascertain this since left and
  234.  right eye must match the stereo emitter.  If this is the case its
  235.  relatively easy to swap the images to correct this problem.
  236.  
  237.  There is a known problem using setmon on XZ/Elan/Express graphics 
  238.  under IRIX 5.1.  This problem may result in a graphics hang and/or
  239.  Xsgi crash when using setmon.  This problem is fixed in IRIX 5.2. 
  240.  
  241.  offstereo always returns the display to 60hz mode which may not
  242.  be the normal mode, especaillay on Reality Engine.
  243.  
  244.  If you use autoplacement on 4Dwm the nestedcubes window may be placed
  245.  out of view.
  246.